<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.memmap &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" >
    <link rel="index" title="Index" href="../../genindex.html" >
    <link rel="search" title="Search" href="../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../index.html" >
    <link rel="up" title="Standard array subclasses" href="../arrays.classes.html" >
    <link rel="next" title="numpy.memmap.flush" href="numpy.memmap.flush.html" >
    <link rel="prev" title="numpy.bmat" href="numpy.bmat.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../index.html">
      <img border=0 alt="NumPy" src="../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../arrays.html" >Array objects</a></li>
          <li class="active"><a href="../arrays.classes.html" accesskey="U">Standard array subclasses</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy.memmap.flush.html" title="numpy.memmap.flush"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="numpy.bmat.html" title="numpy.bmat"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="numpy.bmat.html"
                        title="previous chapter">numpy.bmat</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy.memmap.flush.html"
                        title="next chapter">numpy.memmap.flush</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-memmap">
<h1>numpy.memmap<a class="headerlink" href="#numpy-memmap" title="Permalink to this headline">¶</a></h1>
<dl class="class">
<dt id="numpy.memmap">
<em class="property">class </em><code class="sig-prename descclassname">numpy.</code><code class="sig-name descname">memmap</code><a class="reference external" href="https://github.com/numpy/numpy/blob/v1.18.1/numpy/__init__.py"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#numpy.memmap" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a memory-map to an array stored in a <em>binary</em> file on disk.</p>
<p>Memory-mapped files are used for accessing small segments of large files
on disk, without reading the entire file into memory.  NumPy’s
memmap’s are array-like objects.  This differs from Python’s <code class="docutils literal notranslate"><span class="pre">mmap</span></code>
module, which uses file-like objects.</p>
<p>This subclass of ndarray has some unpleasant interactions with
some operations, because it doesn’t quite fit properly as a subclass.
An alternative to using this subclass is to create the <code class="docutils literal notranslate"><span class="pre">mmap</span></code>
object yourself, then create an ndarray with ndarray.__new__ directly,
passing the object created in its ‘buffer=’ parameter.</p>
<p>This class may at some point be turned into a factory function
which returns a view into an mmap buffer.</p>
<p>Delete the memmap instance to close the memmap file.</p>
<dl class="field-list">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl>
<dt><strong>filename</strong><span class="classifier">str, file-like object, or pathlib.Path instance</span></dt><dd><p>The file name or file object to be used as the array data buffer.</p>
</dd>
<dt><strong>dtype</strong><span class="classifier">data-type, optional</span></dt><dd><p>The data-type used to interpret the file contents.
Default is <code class="xref py py-obj docutils literal notranslate"><span class="pre">uint8</span></code>.</p>
</dd>
<dt><strong>mode</strong><span class="classifier">{‘r+’, ‘r’, ‘w+’, ‘c’}, optional</span></dt><dd><p>The file is opened in this mode:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 9%" />
<col style="width: 91%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p>‘r’</p></td>
<td><p>Open existing file for reading only.</p></td>
</tr>
<tr class="row-even"><td><p>‘r+’</p></td>
<td><p>Open existing file for reading and writing.</p></td>
</tr>
<tr class="row-odd"><td><p>‘w+’</p></td>
<td><p>Create or overwrite existing file for reading and writing.</p></td>
</tr>
<tr class="row-even"><td><p>‘c’</p></td>
<td><p>Copy-on-write: assignments affect data in memory, but
changes are not saved to disk.  The file on disk is
read-only.</p></td>
</tr>
</tbody>
</table>
<p>Default is ‘r+’.</p>
</dd>
<dt><strong>offset</strong><span class="classifier">int, optional</span></dt><dd><p>In the file, array data starts at this offset. Since <em class="xref py py-obj">offset</em> is
measured in bytes, it should normally be a multiple of the byte-size
of <a class="reference internal" href="numpy.dtype.html#numpy.dtype" title="numpy.dtype"><code class="xref py py-obj docutils literal notranslate"><span class="pre">dtype</span></code></a>. When <code class="docutils literal notranslate"><span class="pre">mode</span> <span class="pre">!=</span> <span class="pre">'r'</span></code>, even positive offsets beyond end of
file are valid; The file will be extended to accommodate the
additional data. By default, <code class="docutils literal notranslate"><span class="pre">memmap</span></code> will start at the beginning of
the file, even if <code class="docutils literal notranslate"><span class="pre">filename</span></code> is a file pointer <code class="docutils literal notranslate"><span class="pre">fp</span></code> and
<code class="docutils literal notranslate"><span class="pre">fp.tell()</span> <span class="pre">!=</span> <span class="pre">0</span></code>.</p>
</dd>
<dt><strong>shape</strong><span class="classifier">tuple, optional</span></dt><dd><p>The desired shape of the array. If <code class="docutils literal notranslate"><span class="pre">mode</span> <span class="pre">==</span> <span class="pre">'r'</span></code> and the number
of remaining bytes after <em class="xref py py-obj">offset</em> is not a multiple of the byte-size
of <a class="reference internal" href="numpy.dtype.html#numpy.dtype" title="numpy.dtype"><code class="xref py py-obj docutils literal notranslate"><span class="pre">dtype</span></code></a>, you must specify <a class="reference internal" href="numpy.shape.html#numpy.shape" title="numpy.shape"><code class="xref py py-obj docutils literal notranslate"><span class="pre">shape</span></code></a>. By default, the returned array
will be 1-D with the number of elements determined by file size
and data-type.</p>
</dd>
<dt><strong>order</strong><span class="classifier">{‘C’, ‘F’}, optional</span></dt><dd><p>Specify the order of the ndarray memory layout:
<a class="reference internal" href="../../glossary.html#term-row-major"><span class="xref std std-term">row-major</span></a>, C-style or <a class="reference internal" href="../../glossary.html#term-column-major"><span class="xref std std-term">column-major</span></a>,
Fortran-style.  This only has an effect if the shape is
greater than 1-D.  The default order is ‘C’.</p>
</dd>
</dl>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><code class="xref py py-obj docutils literal notranslate"><span class="pre">lib.format.open_memmap</span></code></dt><dd><p>Create or load a memory-mapped <code class="docutils literal notranslate"><span class="pre">.npy</span></code> file.</p>
</dd>
</dl>
</div>
<p class="rubric">Notes</p>
<p>The memmap object can be used anywhere an ndarray is accepted.
Given a memmap <code class="docutils literal notranslate"><span class="pre">fp</span></code>, <code class="docutils literal notranslate"><span class="pre">isinstance(fp,</span> <span class="pre">numpy.ndarray)</span></code> returns
<code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
<p>Memory-mapped files cannot be larger than 2GB on 32-bit systems.</p>
<p>When a memmap causes a file to be created or extended beyond its
current size in the filesystem, the contents of the new part are
unspecified. On systems with POSIX filesystem semantics, the extended
part will be filled with zero bytes.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">12</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;float32&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">data</span><span class="o">.</span><span class="n">resize</span><span class="p">((</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">))</span>
</pre></div>
</div>
<p>This example uses a temporary file so that doctest doesn’t write
files to your directory. You would use a ‘normal’ filename.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">tempfile</span> <span class="kn">import</span> <span class="n">mkdtemp</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">os.path</span> <span class="k">as</span> <span class="nn">path</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">filename</span> <span class="o">=</span> <span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">mkdtemp</span><span class="p">(),</span> <span class="s1">&#39;newfile.dat&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Create a memmap with dtype and shape that matches our data:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fp</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">memmap</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;float32&#39;</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;w+&#39;</span><span class="p">,</span> <span class="n">shape</span><span class="o">=</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fp</span>
<span class="go">memmap([[0., 0., 0., 0.],</span>
<span class="go">        [0., 0., 0., 0.],</span>
<span class="go">        [0., 0., 0., 0.]], dtype=float32)</span>
</pre></div>
</div>
<p>Write data to memmap array:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fp</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span><span class="p">[:]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fp</span>
<span class="go">memmap([[  0.,   1.,   2.,   3.],</span>
<span class="go">        [  4.,   5.,   6.,   7.],</span>
<span class="go">        [  8.,   9.,  10.,  11.]], dtype=float32)</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fp</span><span class="o">.</span><span class="n">filename</span> <span class="o">==</span> <span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Deletion flushes memory changes to disk before removing the object:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">del</span> <span class="n">fp</span>
</pre></div>
</div>
<p>Load the memmap and verify data was stored:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">newfp</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">memmap</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;float32&#39;</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;r&#39;</span><span class="p">,</span> <span class="n">shape</span><span class="o">=</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">newfp</span>
<span class="go">memmap([[  0.,   1.,   2.,   3.],</span>
<span class="go">        [  4.,   5.,   6.,   7.],</span>
<span class="go">        [  8.,   9.,  10.,  11.]], dtype=float32)</span>
</pre></div>
</div>
<p>Read-only memmap:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fpr</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">memmap</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;float32&#39;</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;r&#39;</span><span class="p">,</span> <span class="n">shape</span><span class="o">=</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fpr</span><span class="o">.</span><span class="n">flags</span><span class="o">.</span><span class="n">writeable</span>
<span class="go">False</span>
</pre></div>
</div>
<p>Copy-on-write memmap:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fpc</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">memmap</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;float32&#39;</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;c&#39;</span><span class="p">,</span> <span class="n">shape</span><span class="o">=</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fpc</span><span class="o">.</span><span class="n">flags</span><span class="o">.</span><span class="n">writeable</span>
<span class="go">True</span>
</pre></div>
</div>
<p>It’s possible to assign to copy-on-write array, but values are only
written into the memory copy of the array, and not written to disk:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fpc</span>
<span class="go">memmap([[  0.,   1.,   2.,   3.],</span>
<span class="go">        [  4.,   5.,   6.,   7.],</span>
<span class="go">        [  8.,   9.,  10.,  11.]], dtype=float32)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fpc</span><span class="p">[</span><span class="mi">0</span><span class="p">,:]</span> <span class="o">=</span> <span class="mi">0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fpc</span>
<span class="go">memmap([[  0.,   0.,   0.,   0.],</span>
<span class="go">        [  4.,   5.,   6.,   7.],</span>
<span class="go">        [  8.,   9.,  10.,  11.]], dtype=float32)</span>
</pre></div>
</div>
<p>File on disk is unchanged:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fpr</span>
<span class="go">memmap([[  0.,   1.,   2.,   3.],</span>
<span class="go">        [  4.,   5.,   6.,   7.],</span>
<span class="go">        [  8.,   9.,  10.,  11.]], dtype=float32)</span>
</pre></div>
</div>
<p>Offset into a memmap:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fpo</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">memmap</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;float32&#39;</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;r&#39;</span><span class="p">,</span> <span class="n">offset</span><span class="o">=</span><span class="mi">16</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fpo</span>
<span class="go">memmap([  4.,   5.,   6.,   7.,   8.,   9.,  10.,  11.], dtype=float32)</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Attributes</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>filename</strong><span class="classifier">str or pathlib.Path instance</span></dt><dd><p>Path to the mapped file.</p>
</dd>
<dt><strong>offset</strong><span class="classifier">int</span></dt><dd><p>Offset position in the file.</p>
</dd>
<dt><strong>mode</strong><span class="classifier">str</span></dt><dd><p>File mode.</p>
</dd>
</dl>
</dd>
</dl>
<p class="rubric">Methods</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="numpy.memmap.flush.html#numpy.memmap.flush" title="numpy.memmap.flush"><code class="xref py py-obj docutils literal notranslate"><span class="pre">flush</span></code></a>(self)</p></td>
<td><p>Write any changes in the array to the file on disk.</p></td>
</tr>
</tbody>
</table>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>